Eight tasks, each ending in an independently testable deliverable:

1. Make the db interface async (SQLite unchanged underneath) - 292 call sites
2. Split db.js into facade + SQLite driver + schema module
3. Postgres test harness: Testcontainers, per-file databases, CI matrix
4. Postgres schema and driver, gated by a cross-dialect parity test
5. The identities auth split, with in-place upgrades for both backends
6. The SQLite to Postgres migrator, verified before COMMIT
7. Auto-migration on boot behind guards
8. Deployment config, Unraid runbook, smoke suites against Postgres

Task 1 is deliberately alone: mixing the async refactor with the driver split
would make the diff unreviewable.

Two landmines found while writing this that the spec had not caught, both
silent-corruption class rather than crash class:

- pg returns BIGINT as a string by default. Every epoch-ms column here is
  BIGINT and every consumer does arithmetic on it, so the int8 type parser
  has to be registered before the first query runs.
- Postgres folds unquoted identifiers to lowercase, so listLeaderboard's
  'AS userId' would return 'userid' and every rungsClaimed would read
  undefined on a leaderboard that still rendered.

Both are pinned by tests/db.parity.test.js.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Every server/db.js export returns a Promise; all call sites across
server/ and tests/ now await. better-sqlite3 remains the implementation, so
behaviour is unchanged - this is purely the shape change that lets a pg
driver slot in behind the same interface.

shared/ is deliberately untouched and stays synchronous: the client bundles
it, and an async reducer would be a far larger change than this migration
needs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Pure refactor - no SQL changes. server/db.js is now a re-export shim so every
existing import path keeps working, while server/db/ holds the seam the
Postgres driver plugs into next.

Adds a schema_migrations table: the schema has outgrown what CREATE TABLE IF
NOT EXISTS plus guarded ALTERs can honestly express, and the identities split
needs a real version marker.

Also extracts server/db/shared.js: findAvailableUsername, parseEventRow, and
the putEvent/upsertParticipation row normalizers are dialect-free logic the
Postgres driver will need identically, so they live once instead of being
duplicated (and drifting) per driver. findAvailableUsername is now async and
awaits its isTaken predicate - harmless for SQLite's synchronous predicate,
required for Postgres's async one - so one implementation serves both.

Static `import { driver } from '../server/db/index.js'` is hoisted by the
ESM spec above the `process.env.DB_PATH = ':memory:'` assignment earlier in
the same file, so it stood up the driver (and its data/rackstack.db file)
against the real default path instead of an in-memory DB - polluting a
real on-disk file across test runs and producing state leakage between
tests. Pull `driver` off the existing dynamic `dbMod` import instead, same
as every other export these files already consume that way.

Caught by rerunning tests/db.test.js in isolation during self-review: it
failed deterministically (config/roles state carried over from a prior
run) even though the full `npm test` run had passed, because npm test's
earlier passing run happened to be the one that created the stray file.

Code review finding: the function has been async (it awaits the shared,
async findAvailableUsername) since this refactor split it out of db.js, so
the inherited "Sync" suffix was false - misleading for Task 4's Postgres
driver author, who needs this exact seam. Renamed in schema.sqlite.js and
updated its one call site in applySchema. driver.sqlite.js imports it
aliased (dedupeUsernamesSchema) so it doesn't shadow the driver's own
dedupeUsernames interface method, which stays a thin, now explicitly
awaited, delegation to it (was a bare `return dedupeUsernamesSync(db)`,
inconsistent with the explicit awaits elsewhere in the same file).

Testcontainers locally, a service container in CI, and a per-test-file
database so the 19 db-touching suites cannot see each other's rows.

The matrix exists because we ship two backends: a SQLite driver that CI never
exercises would drift from the Postgres one, and dialect drift is the bug
class that loses data.

Locally, the only container runtime available is rootless Podman (no docker
binary), so pg-global.js points DOCKER_HOST at the Podman socket and disables
Ryuk when the developer hasn't already set either - Testcontainers then works
unmodified on Docker or Podman. Ryuk's absence makes teardown() the only
thing that stops/removes the container; StartedTestContainer#stop() removes
volumes too, so no reaper is required as long as teardown runs.

No Postgres driver exists yet (that's Task 4), so tests/harness.test.js is
the only suite that actually exercises TEST_DATABASE_URL right now - the
other 452 tests hardcode DB_PATH=':memory:' and keep running against SQLite
regardless of TEST_BACKEND.

Both backends now satisfy the same interface and the full suite runs against
each. tests/db.parity.test.js pins the behaviours that differ between the
dialects and would otherwise fail silently in production:

- pg returns BIGINT as a string by default; every epoch-ms column in this
  schema is BIGINT, so the int8 type parser is registered before any query.
- Postgres folds unquoted identifiers to lowercase, so listLeaderboard's
  camelCase aliases are double-quoted - unquoted, the client receives
  'userid' and every rungsClaimed reads undefined.
- config_history ordered by rowid on SQLite; Postgres has none, so it gains
  a BIGSERIAL key and the admin rollback UI keeps its newest-first order.
- COLLATE NOCASE becomes a unique functional index on lower(username).
- SQLITE_CONSTRAINT_UNIQUE becomes SQLSTATE 23505 - that retry path is what
  keeps a display-name collision from locking a player out on login.

Also points all 13 db-touching test files at provisionDatabase() instead of
hardcoding DB_PATH=':memory:', so npm test genuinely exercises Postgres
instead of silently falling back to SQLite regardless of TEST_BACKEND.
tests/db.test.js and tests/db.events.test.js gain Postgres-branch schema
introspection (pg_tables/information_schema vs. sqlite_master/PRAGMA); the
two guarded-ALTER tests are SQLite-only (schema.pg.js has no ALTER history
to replay) and skip on pg via it.runIf.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Critical: an ambient DATABASE_URL was never cleared on the sqlite test
path, and server/db/index.js checks it before DB_PATH - so a developer
with DATABASE_URL exported (plausible mid-migration, and the var Task 8
documents for production) would have every "sqlite" test file silently
connect to that real database instead. Centralized all env-var writing
for both backends inside provisionDatabase() itself (the pg branch is now
the only writer of DATABASE_URL in the codebase; the sqlite branch clears
it), removing the duplicated per-file if/else from all 14 test files.
Covered by a new regression test in tests/harness.test.js that sets
DATABASE_URL to an RFC-2606-reserved unreachable host and proves the
facade still resolves to sqlite end-to-end, plus a deliberate full
`npm run test:sqlite` run with that bogus DATABASE_URL exported (464/464
green in under 2s - no connection ever attempted).

Important: extracted dedupeUsernames' suffixing walk (identical in both
drivers apart from the SQL) into shared.js's dedupeUsernameRows, so the
-2/-3 convention can't drift between drivers again. Replaced the false
"exercised elsewhere in this suite" claim on db.test.js's guarded-ALTER
skip with a real cross-backend test that calls applySchema() a second
time against an already-populated database - the actual production
restart path - on both backends.

Minor: fixed db.parity.test.js's beforeAll/afterAll split (a RED-path
import failure left `db` undefined, so afterAll's TypeError masked the
real error and skipped cleanup) by switching to a top-level import like
every other rewired file; added ORDER BY tie-breakers to driver.pg.js's
listEvents/getAllUsersWithSaves so ties sort deterministically instead of
arbitrarily on Postgres.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

users.id stays 'provider:providerId', so all three foreign keys and
SUPER_ADMIN_IDS keep working untouched - the split is additive from the
application's point of view. upsertUser now resolves through identities and
records last_login_at.

Existing databases are migrated in place on boot. SQLite needs the full
table-rebuild dance because DROP COLUMN is refused while the column
participates in a table-level UNIQUE constraint, and the rebuild is followed
by a foreign_key_check - a violation there would mean orphaned saves. Both
schemas leave their original users CREATE TABLE untouched and migrate the
columns away as a guarded step that runs on every boot, so even a fresh
database exercises the real migration path, not just the dedicated
upgrade-path test.

getAllUsersWithSaves() keeps exposing provider via the user's primary
(earliest-created) identity - identical to the old column's output for
every single-identity user today. New listIdentities(userId) export is
unused until v1.8.

supertokens_user_id ships nullable and unused; v1.8 fills it in.

Written now rather than with Task 8 because the backup half is valid today and
should happen before anything else touches production data.

Leads with a status table making clear the migrator does not exist yet and
Task 5 has open defects, so nobody follows Part B against live data by mistake.

The rollback section names the one-way door explicitly: reverting to SQLite
always works mechanically, because the migration never modifies or deletes that
file, but it is frozen at cutover. Rolling back ten minutes later is free;
rolling back three days later silently discards three days of everyone's
progress with no error shown to anyone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The test added in 7cc2446 renamed `identities` away entirely to force
upsertUser's second write to fail. That also breaks the identity SELECT at
the top of upsertUser, so the miss branch's INSERT INTO users never even
ran - the test passed against both the fixed driver and the old, non-atomic
one, for the wrong reason (nothing to roll back either way).

Replaced with a trigger (SQLite: CREATE TRIGGER ... BEFORE INSERT; pg: a
BEFORE INSERT trigger function) that only fires for one specific
provider_id, so the identity lookup still misses normally, the users
insert still runs, and only the identities insert fails - the actual
failure mode the fix addresses.

Verified directly: reverted driver.sqlite.js and driver.pg.js to their
pre-fix (2f3bfe0) content in turn and reran this test - it now fails on
both, with the orphaned users row as the visible symptom, exactly as
described in the review. Restored the fixed drivers and reran - green on
both. Also reverted schema.sqlite.js's FK-check-inside-the-transaction fix
locally and confirmed the upgrade test's rollback-pinning assertion
(`expect(cols).toContain('provider')`) catches that regression too, before
restoring it.

npm run test:all: sqlite 472/472, pg 469/472 + 3 pre-existing skips.

…the vacuous last_login_at assertion

Two items from re-review:

1. Important (new, introduced by the prior fix round): moving schema.pg.js's
   base users DDL to the post-split shape (last round's Important 4) was
   correct, but it meant migrateIdentities's backfill-and-DROP-COLUMN branch
   became unreachable by any test that boots a driver normally - no pg test
   run ever exercised it anymore, unlike sqlite's dedicated old-shape test
   (which bypasses applySchema's DDL via a raw better-sqlite3 handle and so
   stayed unaffected). Reinstated as a permanent test: builds a genuinely
   pre-split users table directly against a fresh Postgres database (not via
   applySchema), runs applySchema over it, and asserts the columns are
   dropped, the identity backfilled, users.id unchanged, and the save
   preserved byte-for-byte - plus idempotency across two more calls. Gated
   on driver.__backend === 'pg' since no postgres container is even started
   when running the sqlite suite.

2. Minor 7 (still open): the returning-login test's last_login_at assertion
   was `>= ` against its own insert-time baseline, which is trivially true
   even with the UPDATE deleted entirely - the same vacuous-test shape
   caught in the atomicity test last round. Fixed by faking only `Date`
   (vi.useFakeTimers({ toFake: ['Date'] })), advancing the clock a real 50s
   between the two upsertUser calls, and asserting the exact resulting
   value - only true if the UPDATE actually ran and actually wrote it.

Both verified to fail against the un-fixed code before being finalized:
- Reverted schema.pg.js's backfill (kept the DROP COLUMN, removed the
  INSERT) -> new pg upgrade test fails with the identity row missing.
- Removed the `UPDATE identities SET last_login_at` statement from both
  drivers in turn -> the fake-timer assertion fails with the stale
  insert-time value on both backends.
All reverts restored before this commit; git diff against HEAD was empty
for every production file both times.

npm run test:all: sqlite 472/473 (1 skipped - pg-only test), pg 470/473
(3 skipped - pre-existing sqlite-only tests).